Opi luomaan tehokkaita API-päätepisteitä Next.js Route Handlereiden avulla. Tämä opas kattaa kaiken perusasetuksista edistyneisiin tekniikoihin, sisältäen käytännön esimerkkejä ja parhaita käytäntöjä.
Next.js Route Handlerit: Kattava opas API-päätepisteiden luomiseen
Next.js on mullistanut tavan, jolla rakennamme verkkosovelluksia tehokkailla ominaisuuksillaan, kuten palvelinpuolen renderöinnillä, staattisten sivustojen generoinnilla ja nyt, Route Handlereilla. Route Handlerit tarjoavat joustavan ja tehokkaan tavan luoda API-päätepisteitä suoraan Next.js-sovelluksesi sisällä. Tämä opas tutkii Route Handlereiden konseptia, niiden etuja ja kuinka niitä käytetään tehokkaasti vankkojen API-rajapintojen rakentamiseen.
Mitä ovat Next.js Route Handlerit?
Route Handlerit ovat Next.js-projektin app
-hakemistossa määriteltyjä funktioita, jotka käsittelevät saapuvia HTTP-pyyntöjä. Toisin kuin vanhempi pages/api
-lähestymistapa (joka käyttää API-reittejä), Route Handlerit tarjoavat virtaviivaisemman ja joustavamman tavan määrittää API-päätepisteitä React-komponenttiesi rinnalla. Ne ovat olennaisesti serverless-funktioita, jotka suoritetaan reunalla (edge) tai valitsemassasi palvelinympäristössä.
Ajattele Route Handlereita Next.js-sovelluksesi backend-logiikkana, joka vastaa pyyntöjen käsittelystä, tietokantojen kanssa toimimisesta ja vastausten palauttamisesta.
Route Handlereiden käytön edut
- Yhteissijoittelu: Route Handlerit sijaitsevat suoraan React-komponenttiesi rinnalla
app
-hakemistossa, mikä edistää parempaa organisointia ja koodin ylläpidettävyyttä. - TypeScript-tuki: Sisäänrakennettu TypeScript-tuki takaa tyyppiturvallisuuden ja parantaa kehittäjäkokemusta.
- Middleware-integraatio: Integroi helposti middleware-ohjelmistoja tehtäviin, kuten autentikointiin, auktorisointiin ja pyyntöjen validointiin.
- Striimaustuki: Route Handlerit voivat striimata dataa, mikä mahdollistaa vastausten lähettämisen inkrementaalisesti, mikä on hyödyllistä suurille datajoukoille tai pitkäkestoisille prosesseille.
- Edge-funktiot: Ota Route Handlerit käyttöön Edge-funktioina matalan viiveen vastauksille lähempänä käyttäjiäsi, hyödyntäen globaaleja CDN-verkkoja.
- Yksinkertaistettu API-suunnittelu: Route Handlerit tarjoavat selkeän ja intuitiivisen API:n pyyntöjen ja vastausten käsittelyyn.
- Server Actions -integraatio: Tiivis integraatio Server Actions -toimintojen kanssa mahdollistaa saumattoman kommunikaation asiakaspuolen komponenttien ja palvelinpuolen logiikan välillä.
Next.js-projektin pystyttäminen
Ennen kuin sukellat Route Handlereihin, varmista, että sinulla on Next.js-projekti pystytettynä app
-hakemiston kanssa. Jos aloitat uuden projektin, käytä seuraavaa komentoa:
npx create-next-app@latest my-nextjs-app
Valitse asennusprosessin aikana app
-hakemisto ottaaksesi uuden reititysjärjestelmän käyttöön.
Ensimmäisen Route Handlerin luominen
Luodaan yksinkertainen API-päätepiste, joka palauttaa JSON-vastauksen. Luo uusi hakemisto app
-hakemiston sisään, esimerkiksi /app/api/hello
. Luo tämän hakemiston sisään tiedosto nimeltä route.ts
(tai route.js
, jos et käytä TypeScriptiä).
Tässä on koodi ensimmäiselle Route Handlerillesi:
// app/api/hello/route.ts
import { NextResponse } from 'next/server';
export async function GET(request: Request) {
return NextResponse.json({ message: 'Hello from Next.js Route Handlers!' });
}
Selitys:
import { NextResponse } from 'next/server';
: TuoNextResponse
-olion, jota käytetään API-vastausten rakentamiseen.export async function GET(request: Request) { ... }
: Määrittelee asynkronisen funktion, joka käsittelee GET-pyyntöjä/api/hello
-päätepisteeseen.request
-parametri antaa pääsyn saapuvaan pyyntö-olioon.return NextResponse.json({ message: 'Hello from Next.js Route Handlers!' });
: Luo JSON-vastauksen viestillä ja palauttaa sen käyttämälläNextResponse.json()
-metodia.
Nyt voit käyttää tätä päätepistettä siirtymällä osoitteeseen /api/hello
selaimessasi tai käyttämällä työkalua kuten curl
tai Postman
.
Eri HTTP-metodien käsittely
Route Handlerit tukevat useita HTTP-metodeja, kuten GET, POST, PUT, DELETE, PATCH ja OPTIONS. Voit määrittää erilliset funktiot kullekin metodille samassa route.ts
-tiedostossa.
// app/api/users/route.ts
import { NextResponse } from 'next/server';
export async function GET(request: Request) {
// Logiikka kaikkien käyttäjien hakemiseksi tietokannasta
const users = [{ id: 1, name: 'John Doe' }, { id: 2, name: 'Jane Smith' }]; // Esimerkkidata
return NextResponse.json(users);
}
export async function POST(request: Request) {
const data = await request.json(); // Jäsennä pyynnön runko JSON-muodossa
// Logiikka uuden käyttäjän luomiseksi tietokantaan 'data'-tietojen avulla
const newUser = { id: 3, name: data.name, email: data.email }; // Esimerkki
return NextResponse.json(newUser, { status: 201 }); // Palauta uusi käyttäjä 201 Created -statuskoodilla
}
Selitys:
GET
-funktio hakee listan käyttäjistä (simuloitu tässä) ja palauttaa heidät JSON-vastauksena.POST
-funktio jäsentää pyynnön rungon JSON-muodossa, luo uuden käyttäjän (simuloitu) ja palauttaa uuden käyttäjän 201 Created -statuskoodilla.
Pyyntödatan käsittely
request
-olio tarjoaa pääsyn erilaisiin tietoihin saapuvasta pyynnöstä, mukaan lukien otsakkeet, kyselyparametrit ja pyynnön runko.
Otsakkeet
Voit käyttää pyynnön otsakkeita request.headers
-ominaisuuden avulla:
export async function GET(request: Request) {
const userAgent = request.headers.get('user-agent');
console.log('User Agent:', userAgent);
return NextResponse.json({ userAgent });
}
Kyselyparametrit
Päästäksesi käsiksi kyselyparametreihin voit käyttää URL
-konstruktoria:
export async function GET(request: Request) {
const url = new URL(request.url);
const searchParams = new URLSearchParams(url.search);
const id = searchParams.get('id');
console.log('ID:', id);
return NextResponse.json({ id });
}
Pyynnön runko
POST-, PUT- ja PATCH-pyynnöissä voit käyttää pyynnön runkoa request.json()
- tai request.text()
-metodeilla, riippuen sisällön tyypistä.
export async function POST(request: Request) {
const data = await request.json();
console.log('Data:', data);
return NextResponse.json({ receivedData: data });
}
Vastausten palauttaminen
NextResponse
-oliota käytetään API-vastausten rakentamiseen. Se tarjoaa useita metodeja otsakkeiden, statuskoodien ja vastausrungon asettamiseen.
JSON-vastaukset
Käytä NextResponse.json()
-metodia palauttaaksesi JSON-vastauksia:
return NextResponse.json({ message: 'Success!', data: { name: 'John Doe' } }, { status: 200 });
Tekstivastaukset
Käytä new Response()
-konstruktoria palauttaaksesi pelkkää tekstiä sisältäviä vastauksia:
return new Response('Hello, world!', { status: 200, headers: { 'Content-Type': 'text/plain' } });
Uudelleenohjaukset
Käytä NextResponse.redirect()
-metodia ohjataksesi käyttäjät toiseen URL-osoitteeseen:
import { redirect } from 'next/navigation';
import { NextResponse } from 'next/server';
export async function GET(request: Request) {
return NextResponse.redirect(new URL('/new-location', request.url));
}
Otsakkeiden asettaminen
Voit asettaa mukautettuja otsakkeita käyttämällä headers
-optiota NextResponse.json()
- tai new Response()
-metodeissa:
return NextResponse.json({ message: 'Success!' }, { status: 200, headers: { 'Cache-Control': 'no-cache' } });
Middleware-integraatio
Middleware mahdollistaa koodin suorittamisen ennen kuin pyyntöä käsitellään Route Handlerissasi. Tämä on hyödyllistä autentikointiin, auktorisointiin, lokitukseen ja muihin läpileikkaaviin toimintoihin.
Luodaksesi middlewarin, luo tiedosto nimeltä middleware.ts
(tai middleware.js
) app
-hakemistoon tai mihin tahansa alihakemistoon. Middleware soveltuu kaikkiin reitteihin kyseisessä hakemistossa ja sen alihakemistoissa.
// app/middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
export function middleware(request: NextRequest) {
const token = request.cookies.get('auth-token');
if (!token) {
return NextResponse.redirect(new URL('/login', request.url));
}
return NextResponse.next();
}
export const config = {
matcher: ['/protected/:path*'], // Sovella tätä middlewarea polkuihin, jotka alkavat /protected/
};
Selitys:
middleware
-funktio tarkistaa autentikointitokenin pyynnön evästeistä.- Jos token puuttuu, se ohjaa käyttäjän kirjautumissivulle.
- Muussa tapauksessa se antaa pyynnön edetä Route Handlerille.
config
-olio määrittää, että tätä middlewarea tulisi soveltaa vain reitteihin, jotka alkavat/protected/
.
Virheidenkäsittely
Oikeaoppinen virheidenkäsittely on ratkaisevan tärkeää vankkojen API-rajapintojen rakentamisessa. Voit käyttää try...catch
-lohkoja poikkeusten käsittelyyn ja asianmukaisten virhevastausten palauttamiseen.
export async function GET(request: Request) {
try {
// Simuloi virhettä
throw new Error('Something went wrong!');
} catch (error: any) {
console.error('Error:', error);
return NextResponse.json({ error: error.message }, { status: 500 });
}
}
Selitys:
try...catch
-lohko nappaa kaikki poikkeukset, jotka tapahtuvat Route Handlerin sisällä.catch
-lohkossa virhe kirjataan lokiin, ja palautetaan virhevastaus 500 Internal Server Error -statuskoodilla.
Striimaavat vastaukset
Route Handlerit tukevat striimaavia vastauksia, mikä mahdollistaa datan lähettämisen asiakkaalle inkrementaalisesti. Tämä on erityisen hyödyllistä suurille datajoukoille tai pitkäkestoisille prosesseille.
import { Readable } from 'stream';
import { NextResponse } from 'next/server';
async function* generateData() {
for (let i = 0; i < 10; i++) {
await new Promise(resolve => setTimeout(resolve, 500)); // Simuloi viivettä
yield `Data chunk ${i}\n`;
}
}
export async function GET(request: Request) {
const readableStream = Readable.from(generateData());
return new Response(readableStream, {
headers: { 'Content-Type': 'text/plain; charset=utf-8' },
});
}
Selitys:
generateData
-funktio on asynkroninen generaattori, joka tuottaa datanpaloja viiveellä.Readable.from()
-metodi luo luettavan striimin generaattorista.Response
-olio luodaan luettavan striimin kanssa runkona, jaContent-Type
-otsakkeeksi asetetaantext/plain
.
Autentikointi ja auktorisointi
API-päätepisteiden suojaaminen on ratkaisevan tärkeää. Voit toteuttaa autentikoinnin ja auktorisoinnin käyttämällä middlewarea tai suoraan Route Handlereidesi sisällä.
Autentikointi
Autentikointi vahvistaa pyynnön tehneen käyttäjän henkilöllisyyden. Yleisiä autentikointimenetelmiä ovat:
- JWT (JSON Web Tokens): Luo token onnistuneen kirjautumisen yhteydessä ja vahvista se seuraavissa pyynnöissä.
- Sessiopohjainen autentikointi: Käytä evästeitä sessiotunnisteiden tallentamiseen ja vahvista ne jokaisessa pyynnössä.
- OAuth: Delegoi autentikointi kolmannen osapuolen palveluntarjoajalle, kuten Googlelle tai Facebookille.
Tässä on esimerkki JWT-autentikoinnista middlewarin avulla:
// app/middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import jwt from 'jsonwebtoken';
const secret = process.env.JWT_SECRET || 'your-secret-key'; // Korvaa vahvalla, satunnaisesti generoidulla salasanalla
export function middleware(request: NextRequest) {
const token = request.cookies.get('auth-token')?.value;
if (!token) {
return NextResponse.json({ message: 'Authentication required' }, { status: 401 });
}
try {
jwt.verify(token, secret);
return NextResponse.next();
} catch (error) {
return NextResponse.json({ message: 'Invalid token' }, { status: 401 });
}
}
export const config = {
matcher: ['/api/protected/:path*'],
};
Auktorisointi
Auktorisointi määrittää, mihin resursseihin käyttäjällä on pääsy. Tämä perustuu tyypillisesti rooleihin tai oikeuksiin.
Voit toteuttaa auktorisoinnin Route Handlereidesi sisällä tarkistamalla käyttäjän roolit tai oikeudet ja palauttamalla virheen, jos heillä ei ole pääsyä.
// app/api/admin/route.ts
import { NextResponse } from 'next/server';
export async function GET(request: Request) {
// Oletetaan, että sinulla on funktio käyttäjän roolin saamiseksi tokenista tai sessiosta
const userRole = await getUserRole(request);
if (userRole !== 'admin') {
return NextResponse.json({ message: 'Unauthorized' }, { status: 403 });
}
// Logiikka admin-datan hakemiseksi
const adminData = { message: 'Admin data' };
return NextResponse.json(adminData);
}
async function getUserRole(request: Request): Promise {
// Korvaa tämä todellisella logiikallasi käyttäjän roolin poimimiseksi pyynnöstä
// Tämä voi sisältää JWT-tokenin tarkistamisen tai session tarkistamisen
return 'admin'; // Esimerkki: kovakoodattu rooli esittelyä varten
}
Route Handlereiden käyttöönotto
Route Handlerit otetaan käyttöön serverless-funktioina valitsemallasi hosting-alustalla. Next.js tukee useita käyttöönottopalveluita, kuten Vercel, Netlify, AWS ja muita.
Vercelille käyttöönotto on niin yksinkertaista kuin Git-repositorion yhdistäminen Verceliin ja koodin puskeminen. Vercel tunnistaa automaattisesti Next.js-projektisi ja ottaa Route Handlerisi käyttöön serverless-funktioina.
Edistyneet tekniikat
Edge-funktiot
Route Handlerit voidaan ottaa käyttöön Edge-funktioina, jotka suoritetaan CDN-verkon reunalla, lähempänä käyttäjiäsi. Tämä voi merkittävästi vähentää viivettä ja parantaa suorituskykyä.
Ottaaksesi Route Handlerin käyttöön Edge-funktiona, lisää edge
-ajonaika route.ts
-tiedostoosi:
export const runtime = 'edge';
import { NextResponse } from 'next/server';
export async function GET(request: Request) {
return NextResponse.json({ message: 'Hello from the Edge!' });
}
Server Actions
Server Actions -toiminnot mahdollistavat palvelinpuolen koodin suorittamisen suoraan React-komponenteistasi. Route Handlerit ja Server Actions toimivat saumattomasti yhdessä, mahdollistaen monimutkaisten sovellusten rakentamisen helposti.
Tässä on esimerkki Server Actionin käytöstä Route Handlerin kutsumiseen:
// app/components/MyComponent.tsx
'use client';
import { useState } from 'react';
import { useRouter } from 'next/navigation';
async function handleSubmit(data: FormData) {
'use server';
const name = data.get('name');
const email = data.get('email');
const response = await fetch('/api/users', {
method: 'POST',
body: JSON.stringify({ name, email }),
});
if (response.ok) {
router.refresh(); // Päivitä sivu näyttämään muutokset
}
}
export default function MyComponent() {
const router = useRouter();
return (
);
}
Välimuisti
Välimuistin käyttö voi merkittävästi parantaa API-päätepisteidesi suorituskykyä. Voit käyttää Cache-Control
-otsaketta hallitaksesi, miten vastauksiasi tallennetaan selaimiin ja CDN-verkkoihin.
return NextResponse.json({ message: 'Success!' }, { status: 200, headers: { 'Cache-Control': 'public, max-age=3600' } });
Tämä esimerkki asettaa Cache-Control
-otsakkeen arvoon public, max-age=3600
, mikä kertoo selaimille ja CDN-verkoille, että vastaus voidaan tallentaa välimuistiin tunniksi.
Parhaat käytännöt
- Käytä TypeScriptiä: Hyödynnä TypeScriptin tyyppiturvallisuutta parantaaksesi koodin laatua ja ehkäistäksesi virheitä.
- Validoi pyynnöt: Validoi saapuvat pyynnöt varmistaaksesi datan eheyden ja estääksesi haitallisen syötteen.
- Käsittele virheet siististi: Toteuta asianmukainen virheidenkäsittely tarjotaksesi informatiivisia virheilmoituksia asiakkaille.
- Suojaa päätepisteesi: Toteuta autentikointi ja auktorisointi suojataksesi API-päätepisteesi.
- Käytä middlewarea: Käytä middlewarea läpileikkaaviin toimintoihin, kuten autentikointiin, lokitukseen ja pyyntöjen validointiin.
- Tallenna vastaukset välimuistiin: Käytä välimuistia parantaaksesi API-päätepisteidesi suorituskykyä.
- Valvo API-rajapintojasi: Valvo API-rajapintojasi tunnistaaksesi ja ratkaistaksesi ongelmat nopeasti.
- Dokumentoi API-rajapintasi: Dokumentoi API-rajapintasi, jotta muiden kehittäjien on helppo käyttää niitä. Harkitse työkalujen, kuten Swagger/OpenAPI, käyttöä API-dokumentaatioon.
Esimerkkejä todellisesta maailmasta
Tässä on muutamia esimerkkejä todellisesta maailmasta, kuinka Route Handlereita voidaan käyttää:
- Verkkokaupan API: Luo API-päätepisteitä tuotteiden, tilausten ja käyttäjien hallintaan.
- Sosiaalisen median API: Luo API-päätepisteitä twiittien julkaisemiseen, käyttäjien seuraamiseen ja aikajanojen hakemiseen.
- Sisällönhallintajärjestelmän (CMS) API: Luo API-päätepisteitä sisällön, käyttäjien ja asetusten hallintaan.
- Data-analytiikan API: Luo API-päätepisteitä datan keräämiseen ja analysointiin. Esimerkiksi Route Handler voisi vastaanottaa dataa seurantapikseleistä eri verkkosivustoilta ja yhdistää tiedot raportointia varten.
Kansainvälisen verkkokaupan esimerkki: Route Handler, jota käytetään tuotteiden hintojen hakemiseen käyttäjän maan perusteella. Päätepiste voisi käyttää pyynnön maantieteellistä sijaintia (johdettu IP-osoitteesta) määrittääkseen käyttäjän sijainnin ja palauttaakseen hinnat oikeassa valuutassa. Tämä edistää lokalisoitua ostokokemusta.
Globaalin autentikoinnin esimerkki: Route Handler, joka toteuttaa monivaiheisen tunnistautumisen (MFA) käyttäjille maailmanlaajuisesti. Tämä voisi sisältää tekstiviestikoodien lähettämisen tai autentikointisovellusten käytön, kunnioittaen samalla eri alueiden tietosuojamääräyksiä ja tietoliikenneinfrastruktuureja.
Monikielisen sisällön toimitus: Route Handler, joka toimittaa sisältöä käyttäjän ensisijaisella kielellä. Tämä voidaan määrittää pyynnön `Accept-Language`-otsakkeesta. Tämä esimerkki korostaa asianmukaisen UTF-8-koodauksen ja oikealta vasemmalle -kielituen tarvetta tarvittaessa.
Yhteenveto
Next.js Route Handlerit tarjoavat tehokkaan ja joustavan tavan luoda API-päätepisteitä suoraan Next.js-sovelluksesi sisällä. Hyödyntämällä Route Handlereita voit rakentaa vankkoja API-rajapintoja helposti, sijoittaa backend-logiikkasi React-komponenttiesi rinnalle ja hyödyntää ominaisuuksia, kuten middlewarea, striimausta ja Edge-funktioita.
Tämä kattava opas on käsitellyt kaiken perusasetuksista edistyneisiin tekniikoihin. Noudattamalla tässä oppaassa esitettyjä parhaita käytäntöjä voit rakentaa laadukkaita API-rajapintoja, jotka ovat turvallisia, suorituskykyisiä ja ylläpidettäviä.